class: center, middle, inverse, title-slide .title[ # Report Template ] .subtitle[ ## Introduction of {unhcdown} package ] --- ## Most science is not reproducible  ... even within the same lab group over time! > Your closest collaborator is you 6 months ago, and you don't respond to emails. <small>P. Wilson</small> --- ## Research workflow 1. Prepare data (**EXCEL**) ***  --- ## Research workflow 1. Prepare data (**EXCEL**) 2. Analyse data (**R**) ***  --- ## Research workflow 1. Prepare data (**EXCEL**) 2. Analyse data (**R**) 3. Write report/paper (**WORD**) ***  --- ## This workflow is broken  --- ## Problems of a broken workflow - How did you do this? What analysis is behind this figure? Did you account for ...? - What dataset was used (e.g. final vs preliminary dataset)? - Oops, there is an error in the data. Can you repeat the analysis? And update figures/tables in Word! > A scientific article is advertising, not scholarship. The actual scholarship is the full software environment, code and data, that produced the result. <small>Claerbout & Karrenbach 1992</small> --- ## Rmarkdown to the rescue!  knitr - pandoc - Rstudio --- ## Rmarkdown documents * Fully reproducible (trace all results inc. tables and plots) * Dynamic (regenerate with 1 click) * Suitable for + documents (Word, PDF, etc) + presentations + books + websites + ... --- ## Let's see it in action In Rstudio, create new Rmarkdown document and click on `Knit HTML`. ================= left: 30% Example project: Does sunshine influence happiness? See [myproject.Rmd](myproject.Rmd) ***  --- ## HTML output  --- ## Spotted error in the data? No problem! incremental:true &nbsp; Make changes in Rmarkdown document, click `knit` and report will update automatically! --- ## Other formats: PDF, Word  ***  --- ## Adding citations  See [output](myproject_citations.html)  --- ## Embedding data and Rmd source in HTML report  See [myproject_embed.html](myproject_embed.html) --- ## Interactive documents: Rmarkdown + plotly  [See examples](http://127.0.0.1:4382/ggvis.Rmd) --- ## Give you and your collaborators a little treat  --- ## Convert your old R scripts to Rmarkdown - with [one click in RStudio](http://www.rstudio.com/ide/docs/authoring/markdown_notebooks)  - using `knitr::spin` --- ## Leave behind your current workflow  ## Agenda * Introduction to R Markdown * Dynamic Reporting * Automating Report Generation * Customizing and Styling * Conclusion ## What is R Markdown? * R Markdown is an authoring format that combines code, text, and results in a single document. * It allows you to create reports, presentations, and dashboards with R code and text. ## Basic Structure ```markdown --- title: "My Report" output: html_document --- # Section 1 This is a text section. ``` ## R Markdown Output Formats - R Markdown supports various output formats, such as HTML, PDF, and Word documents. --- ## Report Styling * Customize report style using CSS. * Change fonts, colors, and layouts. --- ## Branding with {unhcrdown} * Add organization logos and headers. * Maintain a consistent look across reports. --- ## Conclusion & Key Takeaways * R Markdown is a versatile tool for report generation. * Parameterized reports enable dynamic customization. * Automate report generation for efficiency. * Customize and brand reports as needed. --- ## Humanitarian Data Product <img src="data:image/png;base64,#img/humprod_unhcr.svg" width="80%" /> --- ## Reproducible pipelines with R markdown or Quarto <img src="data:image/png;base64,#img/tools_change_new.svg" width="70%" /> --- ## Reproducible pipelines with R markdown or Quarto <img src="data:image/png;base64,#img/reproducible_flow_tools.svg" width="100%" /> --- ## Reproducible pipelines with R markdown or Quarto <img src="data:image/png;base64,#img/reproducible_flow_r.svg" width="100%" /> --- ## Get more for less effort: Divisible Content Strategy .pull-left[ .bg-blue[ Nowadays, the average consumer attention span is less than 10 sec. Long reports are therefore less likely to draw large audience. ] “Divisible Content Strategy” consists in breaking a traditional report into a few articles, an infographic, social microcontent, or even a motion graphic video. For instance, if an article includes 5 different charts, each chart can be posted it as a visual tweet implying that the same content can be promoted through different angles. ] .pull-right[  ] --- ## Use microsite A microsite is a single web-page or a small cluster of web pages that exist separate from the organization main website and is used for specific campaign. To this regard a microsite can have its own domain or unique URL and a different and distinctive branding. Microsite can typically be built to highlight content from joint study and research process, following a data collection exercise. Well designed microsite allows to reduce cognitive load, i.e. the amount of working memory resources used to process a piece of information. The better designed is a message the more chances, people will retain it. In order to do that: * Highlight the main __call to action__ in the microsite subtitle * Start with the main __recommendations__ to ensure the readers does not need to wait 10 minutes of reading to find out what the report message is... if not, drop out risk are high.... * Aim to be __minimalistic__: The [ideal length of an article](https://torquemag.io/2018/04/optimal-content-length/) should be between 1500 and 2500 characters, taking an average 7 minutes to read. * Have a 2 or 3 main __top level chapters__ max - avoid presenting content in too many chapter to minimize the cognitive cost for reader to absorb the content. * Minimize __overwhelming effects__ by avoiding putting [too many numbers](https://www.unhcr.org/innovation/wp-content/uploads/2018/02/InnovationYearInReview2017_web.pdf#page=21) to avoid [psychic numbing](https://www.arithmeticofcompassion.org/psychic-numbing) ??? https://github.com/unhcr-americas/ageingonthemove/edit/main/README.md * [Desperate journeys](https://www.unhcr.org/desperatejourneys/) * [Families on the run](https://familiesontherun.org/) * [Her Turn](https://www.unhcr.org/herturn/) * [Stepping Up](https://www.unhcr.org/steppingup/) * [Home Visit Report](https://unhcr-jordan.github.io/home-visit-report) --- ## Publication Tips 1/2 1. Each chapter from the report should behave as an independent article. Reports to be shared through usual publication approach on http://data.unhcr.org . Potentially an EPUB version (for people using e-readers) of the report, in addition of the PDF version can be offered. 2. The full report can be shared within existing platform and sub-articles can be shared in parallel within blogging platform like Medium4 or pre-identified publication partner. 3. Article Headline shall be eye-catching to pique the interest of the audience: Use verbs, keep length under between60–100 characters5. 4. The ideal length of an article should be between 1500 and 2500 characters, taking an average 7 minutes to read6. 5. Charts should be self-explanatory in order to be engaging. This implies to have both a title (with same constraint that a headline, less than 80 char) and sub-title that should act as a short interpretation hint. Chart items should be concise (less than 40 characters). There should be a chart caption stating the reference and date of the data collection as well as the number of observations and confidence interval. A good chart shall deliver a clear message in less than 10 seconds, it is therefore key to adopt a minimalist design. 6. Content shall include integrated social media sharing tools (like “Click to Tweet”) in order to make it easy for readers to share interesting information within the content. Shareable content shall include systematically one graphic from the article as it acts as a powerful micro-content, i.e. teaser for the main story. --- ## Publication Tips 1/2 7. Content shall systematically include a call to action at the end of each article, direct the audience to take the next action: link to donate, link to the full report, link to the most recent appeal or link to subscribe to mailing list. 8. Publication timing should be planned: according to research, the optimal times to publish posts are Monday and Thursday at 9:30 a.m. EST, with most blogs being read at around 11 a.m. 8. Core piece of content shall be tweeted and shared in other social medias 3-4 times the first day using the main angle. The rest of microcontents can be tweeted in the rest of the first week. 9. Notify subscribers once by email, a day after the piece has gone live. This gives some lead time to get the social share numbers up, which increases the chances that others will share. 10. An editorial calendar and media plan should be established in advance so a human story and a Briefing Note can accompany the release of each report --- ## Building Publication-Tailored Content Having refugee and displacement topics in major news channel is key to retain public attention and consequently fundraising. Though in the recent years, the topic of refugees and displacement has tended to enter the list of overly saturated topics. Journalists, publications, and the public want to know the core message as quickly as possible and press release on institutional website do not get maximum audience. Instead of pitching content to publishers post-completion, __bringing publishers into content development__ and ensuring that it will be appealing to their audience from the start has a lot of advantages: Ideas are vetted by the publishing partner (they may have ideas to share as well), content is designed for the publication’s aesthetic and/or preferences, the publisher provides feedback on content iterations, content is typically co-branded. In order to bring the potential journalist and publishers in the content creation, it requires to __pro-actively identify and reach out to them__. As a result, Publication-Tailored content approach greatly increases the likelihood of getting published and reaching out to a larger audience, leveraging the time and energy investment and resulting in more traffic to UNHCR regular communication channel. Continued collaboration with publishers can also change the partnership approach as the same entity can then proactively start asking for high-quality and free content to help support their stories. --- ## Impact measurement of you campaign The following metrics can be potentially measured at Bureau level on the microsite to assess the success of the dissemination strategy. --- class: inverse, center, middle --- ## Notebook for Data Insights documentation: Analysis Repo .pull-left[ > Insight: The capacity to gain an accurate and deep understanding of someone or something Not all charts will emulate need for interpretation - the data analyst need to gemerate the one that can create __debates__. Charts need to be __crafted__ - for instance use chart title framed as "opening question"... Insights arive when a multifunctional team is able to explain __unexpected patterns__, to challenge or revise __existing assumptions__, or to identify evidence to support __Call to action__. ] .pull-right[ .img[] ] ??? https://www.ictworks.org/wp-content/uploads/2021/02/usaid-guide-artificial-intelligence.pdf https://bluemoondigital.co/our-blog/5-elements-storytelling-data/ Check the analysis repo: http://analysis.unhcr.org --- ## Notebook to communicate with data: Microsite .pull-left[ <span style='font-size:30px;'>From __assumptions to evidence__ based statement</span> Data is to support Narrative - not the other way around! Leverage Art Data Storytelling to: * __Explain__, * __Enlighten__, * __Engage__ ] .pull-right[ .img75[] ] ??? See https://github.com/unhcr-americas/ageingonthemove/blob/main/README.md https://distill.pub/2020/communicating-with-interactive-articles/#applications-tab Research Dissemination Conducting novel research requires deep understanding and expertise in a specific area. Once achieved, researchers continue contributing new knowledge for future researchers to use and build upon. Over time, this consistent addition of new knowledge can build up, contributing to what some have called research debt. Not everyone is an expert in every field, and it can be easy to lose perspective and forget the bigger picture. Yet research should be understood by many. Interactive articles can be used to distill the latest progress in various research fields and make their methods and results accessible and understandable to a broader audience. Opportunities Engage and excite broader audience with latest research progress Remove research debt, onboard new researchers Make faster and clearer research progress Challenges No clear incentive structure for researchers Little funding for bespoke research dissemination and communication Not seen as a legitimate research contribution (e.g., to the field, or one's career) --- ## Some useful links - [Rmarkdown by RStudio](http://rmarkdown.rstudio.com/) - [Rmarkdown cheat sheet](http://www.rstudio.com/resources/cheatsheets/) - [Initial steps toward reproducible research](http://kbroman.org/steps2rr/) - [Course on Reproducible Research by K. Broman](http://kbroman.github.io/Tools4RR/) - [Reproducible Research in Coursera](https://www.coursera.org/course/repdata) - [Nice R code](http://nicercode.github.io/guides/reports/) - [Reproducible Research with R and RStudio](http://christophergandrud.github.io/RepResR-RStudio/) - [Ten simple rules for reproducible computational research](http://www.ploscompbiol.org/article/info%3Adoi%2F10.1371%2Fjournal.pcbi.1003285) --- ## More links (software/R packages) - [CRAN Task View on Reproducible Research](http://cran.r-project.org/web/views/ReproducibleResearch.html) - [knitr](http://yihui.name/knitr/) - [pandoc](http://johnmacfarlane.net/pandoc/) - [pander](http://rapporter.github.io/pander/) - [rapport](http://rapport-package.info/) - [reports](http://cran.r-project.org/web/packages/reports/index.html) - [Rgitbook](http://jason.bryer.org/Rgitbook/)